/**
 * 限流装饰器
 * 
 * 该装饰器用于控制API接口的访问频率，防止恶意请求或DoS攻击。
 * 通过在控制器方法上应用此装饰器，可以限制单个用户在特定时间窗口内的请求次数。
 * 
 * 使用方式：
 * @RateLimit({ limit: 5, windowSeconds: 60 }) // 1分钟内最多允许5次请求
 * public async someMethod() { ... }
 */
import 'reflect-metadata';

/**
 * 限流选项接口
 * @property limit - 在时间窗口内允许的最大请求次数
 * @property windowSeconds - 时间窗口大小（秒）
 */
export interface RateLimitOptions {
  limit?: number;           // 默认请求次数限制
  windowSeconds?: number;   // 默认时间窗口（秒）
}

/**
 * 用于存储限流元数据的键
 * 使用Symbol确保唯一性，避免与其他元数据冲突
 */
const RATE_LIMIT_METADATA_KEY = Symbol('rateLimit');

/**
 * 限流装饰器
 * 将限流配置作为元数据附加到目标方法上
 * 
 * @param options - 限流配置选项
 * @returns 方法装饰器
 */
export function RateLimit(options: RateLimitOptions = {}): MethodDecorator {
  return (target, propertyKey, descriptor) => {
    Reflect.defineMetadata(RATE_LIMIT_METADATA_KEY, options, descriptor.value!);
  };
}

/**
 * 获取方法上的限流元数据
 * 供中间件使用，用于获取方法上配置的限流参数
 * 
 * @param target - 目标方法
 * @returns 限流配置选项，如果未设置则返回undefined
 */
export function getRateLimitMetadata(target: any): RateLimitOptions | undefined {
  return Reflect.getMetadata(RATE_LIMIT_METADATA_KEY, target);
} 